Skip to content

chore(physics): post-19.5 housekeeping — physicLabel + ignoreGravity deprecation#1451

Merged
obiot merged 2 commits into
masterfrom
chore/post-19.5-housekeeping
May 17, 2026
Merged

chore(physics): post-19.5 housekeeping — physicLabel + ignoreGravity deprecation#1451
obiot merged 2 commits into
masterfrom
chore/post-19.5-housekeeping

Conversation

@obiot
Copy link
Copy Markdown
Member

@obiot obiot commented May 17, 2026

Three related cleanups against the merged 19.5 PhysicsAdapter API (#1450).

1. physicLabel — adapter identity exposed via world.physic

world.physic used to always be "builtin" (or "none") regardless of which adapter was wired in. Code that wanted to branch on the active physics had to import the concrete class and instanceof it.

New optional PhysicsAdapter.physicLabel field declares the adapter's short identifier:

  • BuiltinAdapter.physicLabel = "builtin"
  • MatterAdapter.physicLabel = "matter"

Application.resolvePhysicSetting reads it and assigns to world.physic, so user code can now branch on the value without imports:

if (app.world.physic === "matter") {
    // matter-only setup (constraints, native queries, …)
}

Falls back to "builtin" for adapters predating the field — existing third-party adapters keep working.

2. World.step gate fix

The conditional in World.step was acting as an "is physics enabled?" flag:

// before
if (this.physic === "builtin") {
    this.adapter.step(dt);
    this.adapter.syncFromPhysics();
}

This worked previously only because world.physic was always "builtin" for any non-"none" case. Under the new labelling that comparison would have stopped stepping the simulation for matter and any third-party adapter. Now reads this.physic !== "none".

The other === "builtin" checks in World (addBody/removeBody's Body Set, the quadtree refresh in update) are genuinely builtin-specific — they read honestly under the new labelling and stay unchanged.

3. Body.ignoreGravity deprecation

Legacy boolean field that only BuiltinAdapter reads; MatterAdapter silently ignores it. Portable equivalent is gravityScale = 0 (or bodyDef.gravityScale = 0 / body.setGravityScale(0)), which works on every adapter.

  • JSDoc marks the field @deprecated since 19.5.0 and points at the portable replacement.
  • Both call sites (BuiltinAdapter.applyGravity, Body.update falling-state machine) keep the dual check for backward compat — ignoreGravity = true still works on builtin.
  • Body.update's falling/jumping state machine now also gates on gravityScale !== 0 so floating bodies (constructed with gravityScale: 0) no longer get marked falling on a side-on collision. Latent bug surfaced while reviewing the deprecation.

Test plan

  • pnpm lint: exit 0
  • pnpm test: 3486 passed, 12 skipped (no behavior change)
  • pnpm --filter melonjs build: clean
  • pnpm --filter @melonjs/matter-adapter build: clean
  • Visual: matter platformer + pool example still run identically
  • Verify app.world.physic === "matter" evaluates true at runtime under matter

CHANGELOG

Two new bullets under 19.5 Fixed and one under Changed.

🤖 Generated with Claude Code

@obiot @claude
chore(physics): post-19.5 housekeeping — physicLabel + ignoreGravity …
ea642b2 
…deprecation

Three related cleanups against the merged 19.5 PhysicsAdapter API.

physicLabel — adapter identity exposed via world.physic
- `world.physic` used to always be `"builtin"` (or `"none"`) regardless
  of which adapter was wired in. User code that wanted to branch on the
  active physics had to import the concrete adapter class and `instanceof`
  it. New optional `PhysicsAdapter.physicLabel` field declares the
  adapter's short identifier — set to `"builtin"` on BuiltinAdapter and
  `"matter"` on MatterAdapter. `Application.resolvePhysicSetting` now
  reads the label and assigns it to `world.physic` so `app.world.physic
  === "matter"` works for branching without an import. Falls back to
  `"builtin"` for adapters predating the field.

World.step gate fix
- `if (this.physic === "builtin")` was acting as an "is physics enabled?"
  flag — worked previously only because the string was always `"builtin"`
  for any non-`"none"` case. Under the new labelling that comparison
  would have stopped stepping the simulation for non-builtin adapters.
  Now reads `if (this.physic !== "none")`. Other `=== "builtin"` checks
  in World (addBody/removeBody, quadtree refresh) are genuinely
  builtin-specific — they read honestly under the new labelling and
  stay unchanged.

Body.ignoreGravity deprecation
- Legacy boolean field that only BuiltinAdapter reads; MatterAdapter
  silently ignores it. Portable equivalent is `gravityScale = 0` (or
  `bodyDef.gravityScale = 0` / `body.setGravityScale(0)`). JSDoc now
  marks the field `@deprecated since 19.5.0` and points to the
  portable replacement. Both call sites keep the dual check for
  backward compat with code that sets `ignoreGravity = true` directly,
  with a comment flagging the redundancy. Body.update's falling/jumping
  state machine now also gates on `gravityScale !== 0` so floating
  bodies (constructed with `gravityScale: 0`) no longer get marked
  "falling" on side-on collisions — was a latent bug.

CHANGELOG: added two new entries under 19.5 Fixed + one under Changed.

Verified:
- pnpm lint: exit 0
- pnpm test: 3486 passed, 12 skipped
- pnpm --filter melonjs build: clean
- pnpm --filter @melonjs/matter-adapter build: clean

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings May 17, 2026 09:56
Copilot AI reviewed May 17, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Post-19.5 housekeeping that exposes adapter identity through world.physic, fixes the World.step gate so it works under any adapter (not just builtin), and deprecates Body.ignoreGravity in favor of the portable gravityScale = 0.

Changes:

  • Add optional PhysicsAdapter.physicLabel, set to "builtin" on BuiltinAdapter and "matter" on MatterAdapter; Application.resolvePhysicSetting propagates it to world.physic with a "builtin" fallback.
  • Change World.step gate from physic === "builtin" to physic !== "none" so the simulation steps under any adapter.
  • JSDoc-deprecate Body.ignoreGravity (recommending gravityScale = 0) and extend Body.update's falling/jumping gate to also check gravityScale !== 0.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file
File Description
packages/melonjs/src/physics/adapter.ts Adds optional physicLabel to the PhysicsAdapter interface with usage docs.
packages/melonjs/src/physics/builtin/builtin-adapter.js Declares physicLabel = "builtin" on the default adapter.
packages/melonjs/src/physics/world.js Updates step gate to physic !== "none"; expands JSDoc on world.physic.
packages/melonjs/src/physics/builtin/body.js Marks ignoreGravity @deprecated; gates falling-state update on gravityScale !== 0 too.
packages/melonjs/src/application/application.ts Resolves legacyString from adapter.physicLabel with "builtin" fallback.
packages/matter-adapter/src/index.ts Declares physicLabel = "matter" on MatterAdapter.
packages/melonjs/CHANGELOG.md Documents the three housekeeping items under 19.5 Fixed/Changed.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@obiot @claude
chore(physics): physicLabel tests + naming + doc CI fix
7710f14 
Folds three follow-ups into the housekeeping PR:

1. Documentation & Examples CI: build matter-adapter before examples.
   The doc workflow built melonjs + debug-plugin + tiled-inflate-plugin
   + spine-plugin then `pnpm -F examples build`. Examples now import
   from `@melonjs/matter-adapter` (platformer-matter + pool-matter)
   and the workflow can't resolve the package without a prior build.
   Failed once on master after the 19.5 merge; added the missing
   `pnpm -F @melonjs/matter-adapter build` step.

2. Test coverage for `physicLabel` propagation:
   - custom adapter with explicit `physicLabel` ⇒ world.physic
     reflects it
   - adapter predating the field (physicLabel undefined) ⇒ falls
     back to "builtin"

3. Naming cleanups:
   - `resolvePhysicSetting` returns `{ adapter, physicLabel }` (was
     `{ adapter, legacyString }`). The variable is no longer a legacy
     flag; it is the identifier.
   - `ApplicationSettings.physic` JSDoc now lists all accepted shapes
     and points at `physicLabel` for the user-facing branching pattern.
   - Application constructor's `world.physic = …` comment rewritten
     to match the new semantics.

Verified:
- pnpm lint: exit 0
- pnpm test: 3488 passed (2 new), 12 skipped
- both melonjs + matter-adapter builds clean

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@obiot obiot merged commit 0e12a03 into master May 17, 2026
6 checks passed
@obiot obiot deleted the chore/post-19.5-housekeeping branch May 17, 2026 10:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@obiot